docs: Add docs about how to get a GtkDevice

Fixes https://bugzilla.gnome.org/show_bug.cgi?id=637895

diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index cc375d7b54c661e70c6aaae5d1b6bcae02d300a2..54cb7fac6e17fe60f5b83dbd4f1ed7aa8c10853e 100644 (file)
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -1044,7 +1044,10 @@ get_native_grab_event_mask (GdkEventMask grab_mask)
 
 /**
  * gdk_device_grab:
- * @device: a #GdkDevice
+ * @device: a #GdkDevice. To get the device you can use gtk_get_current_event_device()
+ *   or gdk_event_get_device() if the grab is in reaction to an event. Also, you can use
+ *   gdk_device_manager_get_client_pointer() but only in code that isn't triggered by a
+ *   #GdkEvent and there aren't other means to get a meaningful #GdkDevice to operate on.
  * @window: the #GdkWindow which will own the grab (the grab window)
  * @grab_ownership: specifies the grab ownership.
  * @owner_events: if %FALSE then all device events are reported with respect to